Changing Monitor Settings

RTX64 monitoring allows you to trace the behavior of your real-time applications by recording significant events that occur during execution of those applications. The events are written to disk, where they are grouped into sessions. Each session corresponds to a single folder that contains one or more files containing events generated during that session. A new session begins each time monitoring is started, and the current session ends each time monitoring is stopped.

There are many different kinds of events. For instance, one kind of event represents the creation of a thread, another represents a fast semaphore being acquired, and another represents a thread exiting a critical section. You can select which kinds of events to be monitored, which allows you to filter out events that are not of interest. Events are stored in each session folder in binary form. You use the RTX64 Monitor Utility to convert a session file into text files showing the details of each event in the order in which the events happened.

In the Control Panel you specify the global, persistent default monitoring settings you want when the Subsystem is started. Default settings consist of: the overall amount of nonpaged memory that the Subsystem will dedicate to collecting monitored events, enabling of monitoring instrumentation, auto-start of monitoring when subsystem starts, the events to monitor, maximum log size, and whether to stop monitoring or delete the oldest log when the memory limit is reached. Once monitoring is started, you can use RTX64 Monitor Utility to dynamically start, stop, and pause monitoring, adjust the events you want to monitor, and convert the binary files in session folders into text files.

NOTE: Monitoring causes as much as one microsecond of latency depending on the real time operation. It is recommended that you only enable and start monitoring during development and that you disable monitoring in production. The amount of latency depends on how many kinds of events are being monitoring and how frequently those events occur in real-time applications. Monitoring fewer kinds of events reduces the impact of monitoring on latency.

Accessing the monitoring settings

Sections in this topic

Configuring the amount of non-paged memory dedicated to monitoring

Enabling and optionally auto-starting monitoring

Configuring the events to trace by default

Customizing session behavior

Configuring the Amount of Non-paged Memory Dedicated to Monitoring

Use the slider to specify the amount of contiguous non-paged memory used by the subsystem for the collection of monitored events. This memory is allocated from nonpaged pool memory and it is allocated when monitoring is enabled. Depending on the number of events you are monitoring and the frequency of those events, you might need to increase this value to avoid receiving Data Lost events due to insufficient internal buffer space. If you encounter Data Lost events, increase the amount of memory dedicated to monitoring (and consider monitoring fewer kinds of events).

Enabling and Optionally Auto-starting Monitoring

Monitoring can be in one of four states: disabled, enabled, started, or paused. Monitoring is disabled by default. Two check boxes determine the state of monitoring when the Subsystem starts:

Enable instrumentation within the Subsystem for tracing real-time applications: Check to enable monitoring when the RTX64 Subsystem starts, and until the Subsystem is stopped again. Enabling does not start monitoring. Enabling only performs the required system setup and preparation, which includes allocating non-paged pool memory dedicated to monitoring. If unchecked, when you start monitoring from RTX64 Monitor Utility, you are warned that doing so will cause a momentary loss of determinism as monitoring passes from disabled to enabled status and then starts.
Automatically start a session on Subsystem start: This check box is disabled until you enable instrumentation. After enabling instrumentation, you can specify that a new monitoring session start automatically when the subsystem starts. If you leave this check box unchecked, you must manually start the monitoring session using either RTX64 Monitor Utility or the real-time API RtMonitorControl.

Configuring the Events to Trace by Default

You can check/uncheck the events you want to monitor. By default, most of the events are checked, except those that are extremely verbose, such as context switch, which can potentially generate many thousands of events per second per core, depending on the value of the HAL timer period. Checking the event category causes all events in that category to be checked.

NOTE: Use the Monitoring events check box to select all or clear all events.

To always monitor network-related events, such as RT-TCP/IP Stack events, select the check box Include network events. When selection of this check box is cleared, network-related events will not be collected, unless they are dynamically included in event collection on a per-session basis through the Monitor utility.

Once monitoring is enabled, any changes to the events selected in the Control Panel do not take effect until you restart the subsystem. Refer to the following tables for a complete description of the events by category.

There are two real-time APIs related to events:

Use RtGenerateEvent to create custom events to instrument your own code.
Use RtMonitorControl to programmatically enable/disable events or start/stop monitoring.

Customizing Session Behavior

By default, monitoring session logs are saved to C:\ProgramData\IntervalZero\Monitor. To change the default, click Browse and select a new location. The path you choose cannot be on a mapped drive and it cannot be a UNC path name.

The maximum session log size by default is 200 MB. You can increase this default to no more than the amount of free space on the drive where the folder is located.

NOTE: A monitor session log can contain multiple session files. The log will contain only the session files that fit under the maximum size until it is determined that the subsequent session file will exceed the maximum. For example, if the maximum session log size is 25MB, and there are session files containing 20MB and 10MB of data respectively, the second session file (10MB) will not be contained in the session log, since it would exceed the 25MB limit when combined with the first session file (20MB).

When the maximum log size is reached you can specify that the system:

Stop the monitoring session.
Discard the oldest event log file and continue the monitoring session. This option effectively creates a sliding time window showing only the most recent N megabytes of events, where N is the maximum log size.

If you start running low on space, you might need to manually delete log files. To delete log files, open Windows Explorer and navigate to folder where session logs are saved (C:\ProgramData\IntervalZero\Monitor by default), and delete as many subfolders as required to free up sufficient disk space. Subfolders use the naming convention YYYYMMDD_HHMMSS_N, where N is an integer between 1 and the total number of monitoring sessions for that second. Do not delete individual binary files within subfolders; you must delete entire subfolders.